Skip to content

[py] Update docstrings (remove reST leftovers and resolve D200) #16525

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 2 commits into from
Oct 29, 2025
Merged

[py] Update docstrings (remove reST leftovers and resolve D200) #16525

merged 2 commits into from
Oct 29, 2025
+21 −19

Conversation

@iampopovich
Copy link
Contributor

@iampopovich iampopovich commented Oct 28, 2025 •
edited by qodo-merge-pro bot
Loading

User description

🔗 Related Issues

relates to #16432

💥 What does this PR do?

This pull request makes minor improvements to code documentation throughout several modules. The main change is the standardization of docstring formatting for class and method documentation, improving readability and consistency.

Documentation standardization:

  • Reformatted class-level docstrings in the BiDi modules (browser.py, input.py, permissions.py, webextension.py) to single-line style for better clarity and consistency. [1] [2] [3] [4]
  • Updated method docstrings in firefox/options.py to use multi-line format with explicit return value descriptions, making documentation more readable. [1] [2] [3]
  • Changed method docstrings in print_page_options.py and script.py to improve formatting and clarity. [1] [2]

🔧 Implementation Notes

i've added D200 rule locally and fixed all warns with no changes in rules in the main repo

💡 Additional Considerations

🔄 Types of changes

  • Cleanup (formatting, renaming)

PR Type

Documentation

Description

  • Standardize docstring formatting to single-line style

  • Convert multi-line docstrings to PEP 257 compliant format

  • Resolve D200 ruff linting warnings across BiDi modules

  • Improve docstring consistency in Firefox and print options

Diagram Walkthrough

flowchart LR
  A["Multi-line docstrings"] -->|Convert to single-line| B["BiDi modules"]
  C["Malformed return docs"] -->|Reformat to PEP 257| D["Firefox & Print options"]
  B --> E["D200 compliance"]
  D --> E
Loading

File Walkthrough
Relevant files
Documentation
browser.py
Standardize Browser class docstring format                             

py/selenium/webdriver/common/bidi/browser.py

  • Converted multi-line class docstring to single-line format
  • Improved readability of Browser class documentation
 +1/-3     
input.py
Standardize Input class docstring format                                 

py/selenium/webdriver/common/bidi/input.py

  • Converted multi-line class docstring to single-line format
  • Enhanced Input class documentation consistency
 +1/-3     
permissions.py
Standardize Permissions class docstring format                     

py/selenium/webdriver/common/bidi/permissions.py

  • Converted multi-line class docstring to single-line format
  • Improved Permissions class documentation clarity
 +1/-3     
script.py
Standardize script conversion method docstring                     

py/selenium/webdriver/common/bidi/script.py

  • Converted multi-line method docstring to single-line format
  • Standardized __convert_to_local_value method documentation
 +1/-3     
webextension.py
Standardize WebExtension class docstring format                   

py/selenium/webdriver/common/bidi/webextension.py

  • Converted multi-line class docstring to single-line format
  • Enhanced WebExtension class documentation consistency
 +1/-3     
print_page_options.py
Reformat print options docstring to PEP 257                           

py/selenium/webdriver/common/print_page_options.py

  • Reformatted to_dict method docstring from inline to multi-line format
  • Added explicit Returns section for better PEP 257 compliance
 +4/-1     
options.py
Reformat Firefox options docstrings to PEP 257                     

py/selenium/webdriver/firefox/options.py

  • Reformatted binary_location property docstring to multi-line format
  • Reformatted preferences property docstring to multi-line format
  • Reformatted profile property docstring to multi-line format
  • Added explicit Returns sections for all three properties
 +12/-3   

@selenium-ci selenium-ci added C-py Python Bindings B-devtools Includes everything BiDi or Chrome DevTools related labels Oct 28, 2025
@qodo-merge-pro
Copy link
Contributor

qodo-merge-pro bot commented Oct 28, 2025 •
edited
Loading

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢
No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪
🎫 No ticket provided
  • Create ticket/issue
Codebase Duplication Compliance
⚪
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
🟢
Generic: Meaningful Naming and Self-Documenting Code

Objective: Ensure all identifiers clearly express their purpose and intent, making code
self-documenting

Status: Passed

Generic: Robust Error Handling and Edge Case Management

Objective: Ensure comprehensive error handling that provides meaningful context and graceful
degradation

Status: Passed

Generic: Secure Error Handling

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

Status: Passed

Generic: Secure Logging Practices

Objective: To ensure logs are useful for debugging and auditing without exposing sensitive
information like PII, PHI, or cardholder data.

Status: Passed

Generic: Security-First Input Validation and Data Handling

Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent
vulnerabilities

Status: Passed

⚪
Generic: Comprehensive Audit Trails

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status:
Error context: The raised WebDriverException may represent a critical action outcome without any explicit
logging added in this PR.

Referred Code 
raise WebDriverException(error_message)
  • Update
Compliance status legend 🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

@iampopovich
Copy link
Contributor Author

iampopovich commented Oct 28, 2025

@cgoldberg please review 🙏

@qodo-merge-pro
Copy link
Contributor

qodo-merge-pro bot commented Oct 28, 2025 •
edited
Loading

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Impact
Learned
best practice
Specify to_dict return details

Make the docstring explicit about the returned structure and its mutability to
avoid ambiguity and align with user expectations.

py/selenium/webdriver/common/print_page_options.py [337-342]

 def to_dict(self) -> _PrintOpts:
     """
+    Get the current print configuration.
+
     Returns:
-        A hash of print options configured.
+        _PrintOpts: A dictionary of the configured print options; this is the internal dict and may be mutated by callers.
     """
     return self._print_options
  • Apply / Chat
Suggestion importance[1-10]: 6

__

Why:
Relevant best practice - Keep API and documentation accurate and consistent by using precise, informative docstrings that describe behavior and types rather than generic placeholders.

Low
  • Update

@iampopovich iampopovich changed the title remove reST leftovers and resolve D200 ruff warns [py] remove reST leftovers and resolve D200 ruff warns Oct 28, 2025
navin772
navin772 approved these changes Oct 29, 2025
View reviewed changes
Copy link
Member

@navin772 navin772 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@cgoldberg cgoldberg changed the title [py] remove reST leftovers and resolve D200 ruff warns [py] Update docstrings (remove reST leftovers and resolve D200) Oct 29, 2025
cgoldberg
cgoldberg approved these changes Oct 29, 2025
View reviewed changes
Copy link
Member

@cgoldberg cgoldberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. thanks.

@cgoldberg cgoldberg merged commit 2bc81b8 into SeleniumHQ:trunk Oct 29, 2025
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cgoldberg cgoldberg cgoldberg approved these changes

@navin772 navin772 navin772 approved these changes

Assignees

No one assigned

Labels

B-devtools Includes everything BiDi or Chrome DevTools related C-py Python Bindings Review effort 1/5

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@iampopovich @cgoldberg @navin772 @selenium-ci